Skip to content

Replace Cloudflare Worker with local Claude Agent SDK (zero API costs)#29

Open
ingokpp wants to merge 1 commit intofarzaa:mainfrom
ingokpp:feature/local-claude-no-api-costs
Open

Replace Cloudflare Worker with local Claude Agent SDK (zero API costs)#29
ingokpp wants to merge 1 commit intofarzaa:mainfrom
ingokpp:feature/local-claude-no-api-costs

Conversation

@ingokpp
Copy link
Copy Markdown

@ingokpp ingokpp commented Apr 8, 2026

Not intended for merging — this PR is shared as a reference for anyone who wants to run Clicky with zero API costs using their local Claude Code session. Feel free to cherry-pick ideas or use it as a starting point.

What this does

Replaces the Cloudflare Worker proxy with free, local alternatives — eliminating all external API costs:

  • Claude API → local Node.js server using @anthropic-ai/claude-agent-sdk, which spawns the Claude Code CLI and inherits local session auth (no API key needed)
  • ElevenLabs TTS → macOS NSSpeechSynthesizer with AVSpeechSynthesizer fallback
  • AssemblyAI STT → Apple Speech framework (already existed as fallback, now the default)

The Cloudflare Worker (worker/) is removed entirely.

Why NSSpeechSynthesizer (deprecated) instead of AVSpeechSynthesizer?

Apple deprecated NSSpeechSynthesizer in macOS 14 in favor of AVSpeechSynthesizer. However, AVSpeechSynthesizer cannot access Siri voices — only its own set of compact/enhanced/premium voices, which sound noticeably robotic. NSSpeechSynthesizer uses the system voice configured in Accessibility settings, which includes Siri voices and sounds dramatically better. It still works fine on macOS 14+ despite the deprecation. An AVSpeechSynthesizer fallback is included in case NSSpeechSynthesizer ever stops working.

How to run it

  1. Have Claude Code installed and authenticated (claude auth login)
  2. cd local-server && npm install && npm start
  3. Build and run in Xcode as normal
  4. Enable speech recognition: System Settings → Keyboard → Dictation

Disclaimer

This was built almost entirely using Claude Code (Claude Opus 4.6). The implementation uses the Claude Agent SDK with local session auth, which works for personal use but is not intended for distributed applications per Anthropic's terms.

🤖 Generated with Claude Code

@ingokpp @claude
Replace Cloudflare Worker with local Claude Agent SDK server
1af06c9 
Eliminate all external API costs by replacing the Cloudflare Worker proxy
with local alternatives:

- Claude API → local Node.js server using @anthropic-ai/claude-agent-sdk,
  which spawns the Claude Code CLI and inherits local session auth
- ElevenLabs TTS → macOS NSSpeechSynthesizer (uses system voice including
  Siri voices, with AVSpeechSynthesizer fallback)
- AssemblyAI STT → Apple Speech framework (already existed as fallback,
  now the default)

The Cloudflare Worker is no longer needed — all three API routes are
replaced with free, local alternatives that require no API keys.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@ingokpp ingokpp mentioned this pull request Apr 8, 2026
Open
@qodo-ai-reviewer
Copy link
Copy Markdown

qodo-ai-reviewer commented Apr 26, 2026

Hi, AppleTTSClient sets isSpeaking=true but only clears it via NSSpeechSynthesizerDelegate; if it falls back to AVSpeechSynthesizer there is no completion callback to reset isSpeaking, so CompanionManager can wait forever in scheduleTransientHideIfNeeded().

Severity: action required | Category: correctness

How to fix: Track fallback speech completion

Agent prompt to fix - you can give this to your LLM of choice:

Issue description

AppleTTSClient uses isSpeaking as the source of truth for isPlaying, but only clears isSpeaking via NSSpeechSynthesizerDelegate. When the client falls back to AVSpeechSynthesizer, there is no delegate wired up, so isSpeaking can remain true forever and callers (notably the transient-hide loop) can wait indefinitely.

Issue Context

  • CompanionManager.scheduleTransientHideIfNeeded() loops while ttsClient.isPlaying.
  • AppleTTSClient.isPlaying returns isSpeaking.
  • AppleTTSClient only clears isSpeaking in the NSSpeech delegate bridge.

Fix Focus Areas

  • leanring-buddy/AppleTTSClient.swift[54-86]
  • leanring-buddy/CompanionManager.swift[701-725]

Suggested approach

  • Make AppleTTSClient conform to AVSpeechSynthesizerDelegate and assign fallbackSynthesizer.delegate = self.
  • In speechSynthesizer(_:didFinish:) (AVFoundation delegate), reset isSpeaking on the main actor.
  • Alternatively, if you don’t want to use the delegate, compute isPlaying from the underlying synthesizers’ true playback state (e.g., systemSynthesizer?.isSpeaking + fallbackSynthesizer.isSpeaking) instead of a manual flag.

Found by Qodo. Free code review for open-source maintainers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ingokpp @qodo-ai-reviewer